Release 10.1A: OpenEdge Development:
Progress 4GL Reference

COPY-LOB statement

Copies large object data between BLOBs, CLOBs, MEMPTRs, and LONGCHARs. It also copies large object data to and from the file system, and converts large object data to or from a specified code page.

Note: You cannot copy large object data between BLOBs and CLOBs directly. However, you can copy a BLOB or CLOB to a MEMPTR or LONGCHAR (which converts the data) and then copy the MEMPTR or LONGCHAR to the CLOB or BLOB, respectively.

Syntax

COPY-LOB   [ FROM ] { [ OBJECT ] source-lob | FILE source-filename }      [ STARTING AT n ] [ FOR length ]   TO { [ OBJECT ] target-lob [OVERLAY AT n [TRIM ] ] |      FILE target-filename [ APPEND ] }   [ NO-CONVERT | CONVERT convert-phrase ]   [ NO-ERROR ].

[ OBJECT ] source-lob

The source object to be copied, which can be a MEMPTR or LONGCHAR variable, a BLOB or CLOB database or temp-table field, or a dynamic expression that resolves to a BLOB or CLOB database or temp-table field. The source object data at this location is copied to the specified target object or file.

FILE source-filename

A character expression that specifies the name of a file containing the source object data to be copied. The object data in this source file is copied to the specified target object or file. You can specify an absolute or relative pathname.

Progress raises the ERROR condition if source-filename resolves to the Unknown value (?) or the source file cannot be read.

STARTING AT n

An integer expression indicating a one-based offset position, in the source object or file, from which to start copying. The copy begins at offset 1, by default. Progress raises the ERROR condition if the specified offset position is less than 1, greater than the size of the object or file, or the Unknown value (?).

Note: Offsets are measured in bytes for binary data (BLOB or MEMPTR), and characters for character data (CLOB or LONGCHAR).

FOR length

An integer expression indicating the number of bytes or characters to copy from the source object or file starting at the specified offset position. Progress copies from the specified offset position to the end of the object or file, by default. Progress raises the ERROR condition if the specified length is less than 0, greater than the size of the object or file, or the Unknown value (?).

Note: Offsets are measured in bytes for binary data (BLOB or MEMPTR), and characters for character data (CLOB or LONGCHAR).

[ OBJECT ] target-lob

The target object to receive the copy, which can be a MEMPTR or LONGCHAR variable, a BLOB or CLOB database or temp-table field, or a dynamic expression that resolves to a BLOB or CLOB database or temp-table field. The object data in the specified source object or file is copied to the target object.

If the specified target object does not yet exist, Progress either creates a BLOB or a CLOB, or allocates memory for a MEMPTR or a LONGCHAR. If the specified target object already exists, Progress deletes the object before the copy operation begins, by default. You can specify the OVERLAY AT n option to overlay some portion of an existing target object.

Note: Although Progress allocates memory for a target MEMPTR, you are responsible for freeing that memory.

OVERLAY AT n [ TRIM ]

An overlay position in the target object. Progress copies the source object or file to an existing BLOB, CLOB, MEMPTR, or LONGCHAR target starting at the given position. If the operation results in writing past the end of a target BLOB, CLOB, or LONGCHAR, Progress extends the target object as necessary. If the operation results in writing past the end of a target MEMPTR, Progress raises the ERROR condition.

If the target object does not yet exist, Progress raises the ERROR condition. If the specified overlay position is less than 1, greater than the size of the object, or the Unknown value (?), Progress raises the ERROR condition.

You can specify the TRIM option only if the target object is a BLOB or CLOB. In this case, Progress copies the source object or file to the existing target object and truncates any data remaining in the target object. If the target object is a MEMPTR or LONGCHAR, Progress ignores this option.

FILE target-filename [ APPEND ]

A character expression that specifies the name of the target file to which the object data in the specified source object or file is copied. You can specify an absolute or relative pathname.

If the target file does not exist, Progress creates the file. If the target file exists, and you specify the APPEND option, Progress opens the file and appends the object data to the end of a file. If the target file exists, but you do not specify the APPEND option, Progress creates the target file anew (which overwrites the original file).

If target-filename resolves to the Unknown value (?), or the target file cannot be created or written, Progress raises the ERROR condition.

NO-CONVERT | CONVERT convert-phrase

Lets you specify the character conversion behavior between the source and target objects.

The NO-CONVERT option specifies that no conversions occur. However, if the target is a LONGCHAR or a CLOB, Progress validates the character data based on the target object’s code page. For a CLOB, this is the code page of the CLOB. For a LONGCHAR, this is -cpinternal unless the LONGCHAR’s code page was set using the FIX-CODEPAGE function. If the validation fails, Progress raises the ERROR condition.

The CONVERT option lets you specify how Progress converts object data. Following is the syntax for convert-phrase:

{   [ SOURCE CODEPAGE codepage ]   [ TARGET CODEPAGE codepage ] }

Specify SOURCE CODEPAGE to indicate that a source object is in the specified code page. If you specify TARGET CODEPAGE, Progress converts the target object to the specified code page.

Table 17 lists the default character conversions Progress performs when copying data between the source and target objects. References to CLOBCP and CLOBDB represent CLOB data in either the CLOB’s defined code page or the database's defined code page, respectively. References to the "fixed code page" represent the code page of a target LONGCHAR variable set using the FIX-CODEPAGE function.

Table 17: Default COPY-LOB statement character conversions

When the source object is a ...	And the target object is a ...	Progress converts the source object ...
MEMPTR	LONGCHAR	From -cpinternal to -cpinternal or the fixed code page.
MEMPTR	CLOBDB	From -cpinternal to the database's defined code page.
MEMPTR	CLOBCP	From -cpinternal to the CLOB’s defined code page.
BLOB	LONGCHAR	No conversion, the LONGCHAR is in -cpinternal or the fixed code page.
LONGCHAR	MEMPTR	From the LONGCHAR’s code page to -cpinternal.
LONGCHAR	BLOB	No conversion, the BLOB’s code page is unknown.
LONGCHAR	CLOBDB	From the LONGCHAR’s code page to the database's defined code page.
LONGCHAR	CLOBCP	From the LONGCHAR’s code page to the CLOB’s defined code page.
CLOBDB	MEMPTR	From the database's defined code page to -cpinternal.
CLOBDB	LONGCHAR	From the database's defined code page to -cpinternal or the fixed code page.
CLOBCP	MEMPTR	From the CLOB’s defined code page to -cpinternal.
CLOBCP	LONGCHAR	No conversion, or conversion to the fixed code page.

Note: If either the source or target object is a file, the target’s code page defaults to -cpstream.

NO-ERROR

Suppresses any errors that occur as a result of the copy operation. After the statement completes, you can check the ERROR-STATUS system handle for information about any errors that might have occurred.

Notes

If a source or target object is stored in a database, its record must be available to copy. The lock mode of the record containing the target object must be EXCLUSIVE-LOCK or SHARE-LOCK and upgradeable; otherwise, the COPY-LOB statement raises the ERROR condition.
You can also assign large object data from one BLOB or MEMPTR to another, and one CLOB or LONGCHAR to another, using the = Assignment operator or ASSIGN statement. You cannot use the = Assignment operator or ASSIGN statement to assign large object data between BLOBs or MEMPTRs and CLOBs or LONGCHARs.